unzip rhq-server-*.zip
Before you begin, make sure you download the RHQ server distribution file (which is packaged as a .zip file).
Installing the RHQ Server basically involves four steps. To start quickly follow these quick-install steps. If you have questions then read the details found further down on this page.
Unlike previous RHQ versions, there is no web installer.
If you plan on using an Oracle database for the RHQ backend datastore, you must download and install its driver. See Oracle Driver for more details.
Unzip the RHQ Server in some directory (to be referenced as <rhq-install-dir>)
Edit <rhq-install-dir>/bin/rhq-server.properties so all settings match your environment. See Startup Properties for more information on these settings.
Make sure you set rhq.autoinstall.enabled=true in rhq-server.properties.
Use <rhq-install-dir>/bin/rhq-installer.[sh,bat] --dbpassword=<your password> to find out what your DB password looks like encoded. This command will not edit your rhq-server.properties - it only outputs the value you should use for the value of the property rhq.server.database.password. Take this encoded value and put it in your rhq-server.properties as the value for that property.
Start the RHQ Server
If you are on Linux/UNIX:
Start the server via <rhq-install-dir>/bin/rhq-server.sh start
If you are on Windows:
Run as a service (for details see Installing and Running as a Windows Service):
Open a command window with the "Run as Administrator" option.
Install the server as a service via <rhq-install-dir>/bin/rhq-server.bat install.
Start the server via <rhq-install-dir>\bin\rhq-server.bat start
or Run interactively:
Start the server in a new command window via <rhq-install-dir>\bin\rhq-server-console.bat
Run <rhq-install-dir>/bin/rhq-installer.[sh,bat] to complete the installation
RHQ ships with the application server it needs for the standard installation. In some circumstances, probably not yours, you can install RHQ into an external application server installation. If so then you must set the environment variable JBOSS_HOME or RHQ_SERVER_JBOSS_HOME appropriately. It must point to the installation directory of your existing app server installation. See more below in Installing on top of an external application server.
To install the RHQ Server:
Unzip the RHQ Server distribution file to the directory within which it will be executed from (to be referenced as <rhq-install-dir>). For example, if you want to install the RHQ Server under the /opt directory, place the RHQ Server distribution file in /opt and execute:
unzip rhq-server-*.zip
The directory structure within the zip file ensures that the RHQ Server has a version-specific installation directory name. For example, the above command will create a directory named /opt/rhq-server-4.6.0. The /opt/rhq-server-4.6.0 directory should not exist prior to the unzip operation.
Do not install the RHQ Server into a directory with a path longer than about 19 characters (e.g. use C:\rhq rather than C:\Documents and Settings\myusername). Excessively long pathnames may cause errors during execution of the server - see this Microsoft MSDN article for more information. It has also been seen that unzipping the distribution using 7-Zip may also help avoid the long-pathname problem.
Load <rhq-install-dir>/bin/rhq-server.properties in a text editor and change all the settings so they are correct for your environment. You can leave many of the values as is, but you must ensure things such as the database settings, host and port settings are all correct for your environment. You can read the comments found in the properties file itself for more documentation or you can refer to Startup Properties for more information on these settings.
The value of the property rhq.server.database.password must be encoded. Do not enter your actual database password here. To find out what your DB password is in encoded form, run this command, which outputs what the value of your encoded password should be:
<rhq-install-dir>/bin/rhq-installer.[sh,bat] --dbpassword=<your password>
Once you made sure all settings in rhq-server.properties are correct, you must make sure you set the rhq.autoinstall.enabled property to true.
Run the RHQ Server
The RHQ Server will allocate a large amount of memory to its JVM when it starts up. This is to ensure it can support a fairly large environment. If your machine does not have enough memory and you don't plan on managing a large environment, you can lower the memory requirements of the RHQ Server by editing bin/rhq-server.sh (for UNIX/Linux) or bin/wrapper/rhq-server-wrapper.conf (for Windows) and adjusting the -Xms, -Xmx, -XX:PermSize, -XX:MaxPermSize VM settings. Note that if you lower the memory requirements, you may cause the RHQ Server to hit OutOfMemoryErrors - change these settings at your own risk. See Running the RHQ Server#Setting Environment Variables and Running the RHQ Server#Optional Wrapper Configuration Files
If you are on Linux/UNIX:
Start the server via <rhq-install-dir>/bin/rhq-server.sh start
If you are on Windows:
Run as a service (for details see Installing and Running as a Windows Service):
Open a command window with the "Run as Administrator" option.
Install the server as a service via <rhq-install-dir>/bin/rhq-server.bat install.
Start the server via <rhq-install-dir>\bin\rhq-server.bat start
or Run interactively:
Start the server in a new command window via <rhq-install-dir>\bin\rhq-server-console.bat
Run the RHQ Installer script
You can validate your setup without actually installing. If you pass in the command line option --test (or -t) to the rhq-installer script, it will perform some validation and output information to the console indicating if everything is ready for performing the installation.
If you are on UNIX/Linux:
<rhq-install-dir>/bin/rhq-installer.sh
If you are on Windows:
<rhq-install-dir>\bin\rhq-installer.bat
Once the installer script completes, your RHQ Server will soon be ready. No further work needs to be done.
If, for some reason, the initial installation attempt failed, you can attempt to force a re-installation using the installer's --force command line option. This isn't guaranteed to successfully complete the installation, but it does allow you to re-run the installation. This is useful if, for example, you first attempted to install while your computer's network configuration was invalid. Once you fix your network configuration, you can run rhq-installer.[sh,bat] --force to retry the install.
The steps to upgrade are virtually the same as the steps to install as documented above, so you can follow them. However, there are some things to note if you are upgrading, which are described below.
Make sure you shutdown the old RHQ Server that you want to upgrade.
Make sure you keep a backup copy of your old RHQ Server's rhq-server.properties so you can refer to the values previously used. You will probably want to make most, if not all, values you have in the old properties file to be the same in the new.
In the rare case that you made customizations to the old bin/rhq-server.sh (if on UNIX/Linux) or bin/wrapper/rhq-server-wrapper.conf (if on Windows) files, back them up because you will need to reapply those changes manually.
Do not extract the RHQ Server distribution over top the old RHQ Server distribution you are upgrading. Either extract it in a separate directory or delete the old install directory and extract the new distro in that (now empty) original location.
Do not set rhq.autoinstall.database to the value of "overwrite" since this will purge all the RHQ data in the database and effectively make this a new, clean install and not a true upgrade. Only set this to overwrite if you truly want to start over with a completely clean and empty RHQ database.
Do make sure you set rhq.server.high-availability.name to the original server's name - that is, this should be the same server name of the server you are upgrading. If the previous installed server left this blank, you can leave this blank as well, but you must ensure that the hostname/domain of the machine has not changed. If that did change, you must explicitly put the old name of the server as the value of this property. If this name does not match the previous server's name, you will effectively be adding another server to the RHQ HA Cloud, which is not what you want to do when simply upgrading an already existing server.
If you aren't sure what the name was, you can ask the installer to give you a list of all existing servers currently registered in the RHQ system. You do this via the --listservers (aka -l) command line option to the rhq-installer script:
<rhq-install-dir>/bin/rhq-installer.[sh,bat] --listservers
Due to a change in the JMS implementation, any unprocessed messages will be lost. To ensure messages are processed it is recommended to bring the server to maintenance mode for 2 minutes prior to stopping the server for the upgrade. Alternatively, all agents can be stopped and the server should continue to run for 2 minutes before shutdown. Note that a failure to do so will not endanger your upgrade, it means only that there is a slight chance of a missed alert.
The single configuration file <rhq-install-dir>/bin/rhq-server.properties that was used during installation is also the one you can use to reconfigure the RHQ Server after you've initially run the installation steps above. To change the configuration of the RHQ Server, you edit that file with the new values you want, shutdown the RHQ Server, then restart it.
Due to some limitations within the app server, there are two RHQ settings that will not take effect immediately upon restart if you change their values after the initial installation. These are settings for the web connector's keystore and truststore file locations (rhq.server.tomcat.security.keystore.file and rhq.server.tomcat.security.truststore.file). If you ever need to change those values after you've installed RHQ, you will need to change them in the app server's standalone/configuration/standalone-full.xml file in the <ssl> node of the https <connector>.
You can install the RHQ Server to run when your computer boots up. On Windows, this means installing the RHQ Server to start as a Windows Service. On UNIX, it means installing the RHQ Server startup script as an init.d startup script. To install as a boot-time service on either Windows or UNIX, refer to Running the RHQ Server.
You should read through the notes below before you install RHQ. They provide information that you should know beforehand and some may be relevant to your situation.
If you have not installed your database server or did not create the necessary database or role for use with RHQ, you must do so first before continuing. See Prerequisites#Database.
You can test your database settings without actually installing RHQ by using the --test command line argument to the rhq-installer script. The installer will tell you if the settings are correct or not. If this test fails, check your connection settings in rhq-server.properties and ensure your database server is running.
The username that RHQ will use to connect to the database must be the owner of the RHQ tables.
If you are using an Oracle DB and you are installing for the first time (or you elected to "overwrite" the database schema but there is nothing to overwrite because this is a first-time installation) then you may see error messages in the RHQ logs that look like the following - these can be safely ignored:
ERROR [DBSetup] {DBSetup.dropped-table-error}Failed to drop
table [SOME_RHQ_TABLE] or one of its sequences. Cause: ErrorCode=[2289];
SQLState=[42000]; Message=[ORA-02289: sequence does not exist];
Type=[java.sql.SQLException]
If you are using a PostgreSQL DB, note that there have been some cases where the RHQ installation failed with an error "Relation RHQ_Principal does not exist". Refer to PostgreSQL for a workaround.
If you plan on installing with Oracle as the backend DB, you need to acquire the Oracle JDBC driver from an external source (due to licensing restrictions, RHQ cannot ship with the Oracle JDBC driver). One such place to obtain this driver is Oracle's website. Once you obtain the Oracle JDBC driver jar file, you must copy it to the <rhq-install-dir>/modules/org/rhq/oracle/main directory. You also must make sure the name of the jar matches that in the module.xml file located in the same directory (see the <resource-root> element's "path" attribute). Do this before running the server or installer.
If you do not plan on having an Oracle database, you don't have to do anything. A valid Postgres JDBC driver is included with RHQ out-of-box - Postgres should work without any customizations.
The RHQ Server's rhq.server.high-availability.name property uniquely identifies the RHQ Server being installed. It defaults to the resolved hostname of the machine but can be set to a different value if necessary (it actually doesn't have to be a hostname or IP address at all). If you provide a new name that is different from any other server name registered in your RHQ environment, this will result in a new RHQ Server registration. In other words, the installer treats this as an additional server being added to the RHQ HA Cloud. You can find out all the server names currently registered in your RHQ environment by running:
<rhq-install-dir>/bin/rhq-installer.[sh,bat] --listservers
Avoid using generic names such as server, localhost or s1 for the value of rhq.server.high-availability.name. Use more explicit names that easily identify the RHQ Server - IP addresses, FQDN hostnames or simply more descriptive names are more appropriate.
The server's public endpoint (rhq.autoinstall.public-endpoint-address) is used for the Server-Agent communication. After installation, you can update the Server Endpoint information via the RHQ GUI Administration pages (specifically, Administration>Servers).
The Server Endpoint Address must be public so that all RHQ Agents are able to resolve the supplied value. This is particularly important in High Availability (multi-Server) environments where RHQ Agents are connecting to various RHQ Servers in the cloud.
If you plan on using RHQ's feature of alert email notifications (most people do), you must ensure your SMTP settings are set correctly. Without providing RHQ with a valid SMTP server, it will be unable to send emails. To test your email settings once the RHQ Server is running, log in as the "rhqadmin" user and go to the email test page here: http://localhost:7080/coregui/CoreGUI.html#Test/ServerAccess/EmailTest.
If you are installing on a UNIX/Linux machine, you now have the option to install the RHQ Server on top of an existing, previously installed, application server (aka "EAP" or "WildFly"). If you downloaded the application server installation and unzipped it in some external location (let's say /opt/as), you can set the environment variable JBOSS_HOME to point to that /opt/as directory. You can also target RHQ to be installed on a specific application server installation by setting the RHQ_SERVER_JBOSS_HOME environment variable. RHQ_SERVER_JBOSS_HOME takes precendence; if it is set, it will be used; if it is not set, JBOSS_HOME will be used. If neither is set, RHQ will install within its own, internal application server that ships with the RHQ Server distribution (located at <rhq-server-install-dir>/jbossas). If you want to install in an external application server, you can unzip the RHQ Server distro and exclude the internal application server install that comes with it (via the command unzip <distro.zip> -x '*/jbossas/**') or just "rm -r" the RHQ Server's jbossas directory.
If you are installing on Windows, you cannot install on a separate application server install and the JBOSS_HOME / RHQ_SERVER_JBOSS_HOME environment variables are ignored by RHQ. On Windows, RHQ will only be installable in the application server installation that comes with the RHQ Server distribution.
It is not the purpose of this feature to allow you to install inside an application server that has other applications deployed and running in it. The real reason why this feature exists is it is the start of an implementation to support RPM installations. It is planned for the RHQ Server distribution to be shipped in RPM form sometime in the future and this feature may help with that effort.
It is still required that you run RHQ Server in its own dedicated application server instance, no matter where that application server instance is installed.
RHQ no longer has a GUI installer application. You install via the command line only using the installer script rhq-installer.[sh,bat].
If you are a developer, and have a dev build of RHQ, the installer will run automatically if you run "rhq-server.sh console" or "rhq-server.bat console" (on UNIX and Windows respectively).
You will also notice that the RHQ EAR is not hot deployed by the deployment scanner (that is, the EAR is not located in the app server's deployments/ directory). Rather, our EAR is deployed by our own custom AS startup extension and the EAR itself is found under <rhq-install-dir>/modules, not deployments/ (specifically, the EAR is found in our startup extension module).
If developers wish to hot-deploy changes to code, they can build the RHQ maven modules with the -Pdev profile which will copy the new artifacts to the new startup extension modules location. You can then ask the app server to reload.